View on GitHub

Microservice DSL (MDSL)

A Domain-Specific Language (DSL) to specify (micro-)service contracts, their data representations and API endpoints.

Primer — Endpoint Types — API Provider and Client — Tutorial — Tools —Transformations

Overview

Microservice Domain-Specific Language (MDSL) abstracts from technology-specific interface description languages such as OpenAPI/Swagger, WSDL, and Protocol Buffers.

Important note: All MDSL tools, including validators, quick fix transformations, Freemarker templates, IDL and Java generators, etc. are the output of research projects with limited budgets; at present, resources to continue development and reduce technical debt are sparse. The MDSL tools should be viewed and positioned as technology demonstrators that show how production-ready API-first design tools could look like.

Status: The core MDSL language (data types, endpoint types, protocol bindings) is stable now; a language reference and primer can be found in “Patterns for API Design”. Features such as user stories and flow modeling remain experimental previews.

The “Interface Refactoring Catalog (IRC)” and publications about it feature MDSL snippets.

A First Example

An API with a single endpoint HelloWorldEndpoint that exposes a single operation called sayHello can be modelled as this: 

API description HelloMDSLWorld

data type SampleDTO {ID, D<string>} 

endpoint type HelloWorldEndpoint
exposes 
  operation sayHello 
    expecting payload "in": D<int>  
    delivering payload SampleDTO

API provider HelloWorldAPIProvider
  offers HelloWorldEndpoint 
  at endpoint location "http://localhost:8000" 
  via protocol HTTP 
    binding resource HomeResource at "/"
      operation sayHello to POST 
  
API client HelloWorldAPIClient
  consumes HelloWorldEndpoint 
  from HelloWorldAPIProvider
  via protocol HTTP

sayHello accepts a single scalar string value D<string> as input. This operation returns a Data Transfer Object (DTO) called SampleDTO as output, which is modeled explicitly so that its specification can be reused. This SampleDTO is specified incompletely as an identifier-data pair {ID, D}. Its two elements are an identifier ID and some data D. The names of these two “parameters” have not been specified yet. The data element D is a string; the type of the ID parameter is not unspecified. This is different from "in": D<int>, the data send in the request message of sayHello, which gives its single parameter a name, a role, and a type.

In addition to the endpoint type (a.k.a. service contract) HelloWorldEndpoint, an API client and an API provider working with this contract are defined (and bound to HTTP, a single home resource in this simple case).

Take a look at Hello World in Swagger/OpenAPI Specification in comparison. You can find such contract specification example here (note: this OpenAPI specification contains a few more details about the HTTP binding of the abstract contract).

An advanced example showing more contract feature appears in the MDSL Primer.

Quickstarts

Language Specification Elements

  1. Service endpoint contract types follow this template:
    • endpoint type ... exposes operation ... expecting ... delivering ...
  2. Data contracts (schemas)
    • data type SampleDTO {ID, V} in the above example
  3. Optional instance-level concepts:
    • API Provider with protocol bindings and, optionally, Service Level Agreements and evolution strategies such as Two in Production
    • API Client instances consuming the contracts exposed by providers
    • API Gateways (or intermediaries) acting both in client and in provider role; note that gateways are not featured in the simple example above
  4. Integration scenarios including user/job/test stories
  5. Orchestration flows.

Next Steps

MDSL Tools and Their Application

The following tools already support MDSL:

See MDSL Tools page for more information. Two blog posts, “Story-Driven Service Design: From Feature Story to Minimum Viable API Product” and “Event-Driven Service Design: Five Steps from Whiteboard to OpenAPI and Camel Flow” feature MDSL these tools in action.

MDSL Documentation (this website)

Copyright: Olaf Zimmermann, 2018-2022. All rights reserved. See license information.